0장 한눈에 보기 — 용어집과 이 책의 척추

출처: 원서 『API Design Patterns』(JJ Geewax, Manning). 이 입문판은 8~16장을 다룹니다.

이 장에서 딱 3가지만 1. 8~16장에서 만날 핵심 용어를 미리 쉬운 말로 풀어 둡니다 (모르는 단어로 골치 아플 일 없게). 2. 8~16장이 사실은 하나로 이어진 이야기라는 걸 큰 그림으로 봅니다. 3. 각 장을 한 줄로 요약해서, 지금 어디쯤 가고 있는지 지도를 그려 둡니다.

이 장의 학습 목표는 두 가지입니다. - 8~16장에 나오는 핵심 용어를 한 문장으로 설명한다. - 각 장이 다음 장과 어떻게 이어지는지를 구분한다.

들어가기 전에 — 왜 용어집이 먼저일까?

코딩 책을 펴자마자 "멱등성을 보장하는 사용자 메서드는..." 같은 문장을 만나면 눈앞이 캄캄해진 적 있죠?

단어 하나를 모르면 그 문장 전체가 막히고, 그게 쌓이면 책을 덮게 됩니다.

그래서 이 책은 거꾸로 갑니다. 어려운 용어를 먼저 다 풀어 두고, 본문에서는 마음 편히 읽기만 하면 되도록 했습니다.

각 용어는 세 가지로 설명합니다. - 한 문장 뜻 — 가장 짧은 정의 - 일상비유 — 머릿속에 그림이 그려지는 비유 - 한 줄 예 — 실제로 어떻게 생겼는지 보여 주는 짧은 예

용어로 용어를 설명하지 않습니다. 모르는 단어가 또 나오면 그것도 아래에 있습니다.

큰 그림 먼저 — 이 책이 다루는 세계

본격적인 용어에 들어가기 전에, 딱 한 장면만 상상해 보세요.

우리는 건물 관리 시스템을 만들고 있습니다. 건물에는 사무실이 있고, 사무실에는 책상이 있고, 사람들이 드나듭니다.

이 책 전체가 바로 이 "것들(리소스)"을 어떻게 잘 다룰지에 대한 이야기입니다. 아래 용어들은 모두 이 세계 안의 단어라고 생각하면 편합니다.

용어집 — 28개 핵심 단어

1. 리소스 (Resource)

한 문장 뜻 API가 다루는 "것" 하나하나. 사용자, 채팅방, 강의처럼 이름 붙일 수 있는 명사.

일상비유 호텔의 객실 하나하나가 리소스입니다. 201호, 202호처럼 각자 번호(주소)가 있고, 따로따로 다룰 수 있죠.

한 줄 예 GET /chatRooms/1 — "1번 채팅방(리소스)을 보여줘"

2. 컬렉션 (Collection)

한 문장 뜻 같은 종류의 리소스를 모아 둔 묶음.

일상비유 호텔의 "객실 전체 목록"이 컬렉션입니다. 객실 하나는 리소스, 객실 전부는 컬렉션이에요.

한 줄 예 GET /chatRooms — "모든 채팅방(컬렉션)을 보여줘"

3. 필드 (Field)

한 문장 뜻 리소스가 가진 정보 한 칸. 제목, 설명, 날짜처럼 리소스 안의 항목.

일상비유 객실 정보표의 칸 하나하나입니다. "방 번호" 칸, "전망" 칸, "흡연 여부" 칸 — 이 칸 하나가 필드예요.

한 줄 예 채팅방의 title, description이 각각 필드입니다.

4. 필드 마스크 (Field Mask)

한 문장 뜻 "이 칸들만 다뤄 줘"라고 골라서 알려 주는 이름 목록.

일상비유 마트에서 "우유랑 빵만 주세요"라고 적은 쪽지입니다. 전부가 아니라 필요한 것만 콕 집는 거죠.

한 줄 예 fieldMask=["title"] — "제목 칸만 다뤄 줘"

5. 부분 취득 (Partial Get)

한 문장 뜻 리소스 전체가 아니라 원하는 필드만 가져오는 것.

일상비유 메뉴판 전체 대신 "디저트만 보여 주세요"라고 하는 것. 가져올 게 적으니 가볍고 빠릅니다.

한 줄 예 GET /chatRooms/1?fieldMask=title — 제목만 받아 옴

6. 부분 업데이트 (Partial Update)

한 문장 뜻 리소스 전체를 다시 보내지 않고, 바꿀 필드만 고쳐 주는 것.

일상비유 피자 토핑 하나만 바꾸려는데 "피자 전체를 다시 주문하세요"라고 하면 황당하죠. 부분 업데이트는 "토핑만 바꿔 주세요"가 되는 겁니다.

한 줄 예 PATCH /chatRooms/1?fieldMask=title + {title:"새 제목"} — 제목만 바뀜

7. 표준 메서드 (Standard Method)

한 문장 뜻 어느 API에나 있는 기본 동작 5종 — 만들기·읽기·목록·수정·삭제(CRUD).

일상비유 어느 식당에나 있는 기본 메뉴(밥·국·반찬) 같은 것. 이름만 들어도 무슨 동작인지 누구나 압니다.

한 줄 예 CreateUser, GetUser, ListUsers, UpdateUser, DeleteUser

8. 사용자 메서드 / 맞춤 동작 (Custom Method)

한 문장 뜻 기본 5종으로는 표현할 수 없는 특별한 동작을 위한 메서드. 콜론(:)으로 동작 이름을 붙임.

일상비유 식당의 "셰프 특선 메뉴"입니다. 기본 메뉴로 못 만드는 요리를 따로 내놓는 거죠.

한 줄 예 POST /rockets/123:launch — "123번 로켓을 발사해"

9. 부수 효과 (Side Effect)

한 문장 뜻 요청 하나가 본래 일 말고 추가로 일으키는 다른 일 (이메일 발송, 알림 등).

일상비유 도미노를 하나 쓰러뜨렸더니 옆 도미노까지 줄줄이 넘어가는 것. "하나만 건드렸는데 딴 일이 벌어졌다"가 부수 효과입니다.

한 줄 예 이메일 "보냄"으로 상태를 바꿨더니 실제로 메일이 발송됨

10. 멱등성 (Idempotency)

한 문장 뜻 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 똑같은 성질.

일상비유 엘리베이터 버튼을 다섯 번 눌러도 엘리베이터는 한 번만 옵니다. 몇 번 눌렀든 결과가 같죠 — 그게 멱등성입니다.

한 줄 예 "이 작업 끝났어?"라고 100번 물어봐도 답만 받을 뿐 아무것도 바뀌지 않음

11. 장기 실행 작업 / LRO (Long-Running Operation)

한 문장 뜻 오래 걸리는 작업의 진행 상황을 추적하기 위해 발급되는 "추적표" 리소스.

일상비유 택배 운송장 번호입니다. 물건은 아직 안 왔지만, 번호로 "지금 어디쯤 왔나"를 계속 확인할 수 있죠.

한 줄 예 백업 요청 → Operation{id:"op-1", done:false} 받음 → 나중에 완료 확인

12. 폴링 (Polling)

한 문장 뜻 "끝났어?"라고 주기적으로 직접 물어보며 결과를 확인하는 방식.

일상비유 카운터에 가서 "제 음식 다 됐어요?"라고 몇 번이고 물어보는 것.

한 줄 예 1초마다 GetOperation을 호출해 done이 true인지 확인

13. 대기 / 블로킹 (Waiting / Blocking)

한 문장 뜻 서버가 "끝났어요!"라고 알려 줄 때까지 한 번의 요청으로 기다리는 방식.

일상비유 식당 진동벨입니다. 앉아서 기다리면 다 됐을 때 벨이 울려요. 계속 물어볼 필요가 없죠.

한 줄 예 GET /operations/op-1:wait — 완료될 때까지 응답을 보류했다가 한 번에 받음

14. 재수행 가능 작업 / 멱등 키 (Idempotent Operation)

한 문장 뜻 실수로 두 번 보내도 한 번만 처리되도록, 요청에 붙이는 일회용 표딱지(요청 ID).

일상비유 콘서트 입장 팔찌입니다. 같은 팔찌로는 한 번만 입장돼요. 두 번 긁어도 두 번 들어가지지 않죠.

한 줄 예 요청에 requestId:"abc-123"을 붙이면 같은 ID의 두 번째 요청은 무시됨

15. 서브리소스 (Sub-resource)

한 문장 뜻 어떤 리소스에 딸려 있는 한 단계 아래의 리소스.

일상비유 집(리소스)에 딸린 우편함(서브리소스)입니다. 집과 따로 떼어 생각하기 어렵고, 항상 어느 집에 붙어 있죠.

한 줄 예 /chatRooms/1/config — 1번 채팅방에 딸린 설정(서브리소스)

16. 싱글톤 서브리소스 (Singleton Sub-resource)

한 문장 뜻 부모 리소스마다 딱 하나만 존재하는 서브리소스 (목록도 없고, 만들거나 지우지도 않음).

일상비유 사람마다 가진 "주민등록증"입니다. 한 사람에 정확히 하나, 새로 만들거나 버리는 게 아니라 내용만 고치죠.

한 줄 예 /users/1/settings — 사용자마다 설정은 정확히 하나

17. 교차 참조 / 참조 (Cross-reference)

한 문장 뜻 한 리소스가 다른 리소스를 가리키도록 그 주소(ID)를 필드에 담아 두는 것.

일상비유 책 뒤의 "저자 이름"입니다. 책 안에 저자를 통째로 넣지 않고, "이 저자다"라고 가리키기만 하죠.

한 줄 예 Book { authorId: "authors/kim" } — 책이 저자를 가리킴

18. 일대다 / 다대다 관계 (One-to-many / Many-to-many)

한 문장 뜻 일대다는 "한 쪽이 여럿을 거느림", 다대다는 "양쪽 모두 여럿과 얽힘".

일상비유 일대다는 엄마 한 명과 자녀 여러 명. 다대다는 학생들과 동아리들 — 학생도 여러 동아리에, 동아리도 여러 학생을 가집니다.

한 줄 예 저자 1명 ↔ 책 여러 권(일대다), 학생 여럿 ↔ 강의 여럿(다대다)

19. 연관 리소스 (Association Resource)

한 문장 뜻 다대다 관계 자체를 하나의 독립 리소스로 만든 것. 관계에 딸린 정보까지 담을 수 있음.

일상비유 "수강 등록증"입니다. 학생과 강의를 이어 주면서, 진도율·수료 여부 같은 관계 정보도 함께 적혀 있죠.

한 줄 예 Enrollment { studentId, courseId, progress, completed }

20. 관계 메타데이터 (Relationship Metadata)

한 문장 뜻 관계 그 자체에 대한 추가 정보 (역할, 가입일, 만료일 등).

일상비유 동아리 가입 신청서에 적힌 "직책: 회장, 가입일: 3월"입니다. 학생 정보도 동아리 정보도 아닌, "그 둘의 관계"에 대한 정보죠.

한 줄 예 멤버십의 role:"admin", joinedAt:"2024-03-15"

21. add/remove 동작 (Add/Remove Custom Method)

한 문장 뜻 관계에 딸린 정보가 필요 없을 때, 그냥 "넣기/빼기"만 하는 가벼운 맞춤 동작.

일상비유 좋아요 버튼입니다. 누르면 추가, 다시 누르면 취소 — 그 외에 기록할 정보가 없죠.

한 줄 예 POST /repos/1:addStar, POST /repos/1:removeStar

22. 다형성 (Polymorphism)

한 문장 뜻 한 자리에 여러 종류의 것이 번갈아 들어올 수 있게 하는 설계.

일상비유 콘센트(USB 포트)입니다. 키보드든 마우스든 충전기든, 같은 구멍에 다양한 기기를 꽂을 수 있죠.

한 줄 예 Message { content: TextContent | ImageContent | VideoContent }

23. 읽기 전용 필드 (Read-only Field)

한 문장 뜻 처음 만들 때 정해지고 그 뒤로는 바꿀 수 없는 필드.

일상비유 졸업장에 찍힌 "졸업 연도"입니다. 한 번 정해지면 고치는 게 아니라, 잘못됐으면 새로 발급받아야 하죠.

한 줄 예 멤버십의 userId, groupId는 만든 뒤 변경 불가

24. 무상태 메서드 (Stateless Method)

한 문장 뜻 서버에 아무것도 저장하지 않고, 입력을 받아 결과만 돌려주는 동작.

일상비유 계산기입니다. 숫자를 넣으면 답을 주지만 이전 계산을 기억하지 않죠. (반대로 금고는 넣어 두면 저장됩니다.)

한 줄 예 POST /text:translate — "안녕하세요"를 받아 "Hello"만 돌려주고 끝

25. 앵커 리소스 (Anchor Resource)

한 문장 뜻 저장 안 하는 동작이라도 비용 추적·권한 관리를 위해 슬쩍 매달아 두는 부모 리소스.

일상비유 무인 복사기에 붙은 "사번 입력"입니다. 복사 자체는 기록을 안 남기지만, 누가 얼마나 썼는지는 사번에 매달아 셉니다.

한 줄 예 POST /projects/1/text:translate — 번역은 무상태지만 프로젝트별 사용량을 셈

26. 고유성 제약 (Uniqueness Constraint)

한 문장 뜻 같은 두 리소스를 잇는 관계는 딱 하나만 존재하게 막는 규칙.

일상비유 같은 동아리에 같은 학생을 두 번 가입시킬 수 없는 것. 이미 멤버면 두 번째 신청은 거절됩니다.

한 줄 예 같은 userId+groupId 쌍으로 멤버십을 또 만들면 409 Conflict

27. 별칭 메서드 (Aliased Method)

한 문장 뜻 자주 쓰는 조회를 짧은 전용 메서드로 줄여 둔 것.

일상비유 카페에서 "아아 주세요"라고 줄여 말하는 것. 긴 주문을 매번 외울 필요가 없죠.

한 줄 예 GET /users/jimmy/groups — "지미가 속한 그룹들" (긴 필터 없이)

28. 참조 무결성 (Referential Integrity)

한 문장 뜻 가리키던 대상이 사라졌을 때 가리키는 쪽을 어떻게 처리할지에 대한 규칙.

일상비유 연락처에 저장된 친구가 번호를 없앴을 때, 그 연락처를 지울지·막을지·그냥 둘지 정하는 것.

한 줄 예 멤버가 남아 있는 그룹은 삭제를 막음(제한) — 409 Conflict

잠깐, 자주 헷갈리는 짝 3개만 짚고 가기

용어가 비슷하게 생겨서 헷갈리는 짝이 있습니다. 미리 한 번만 구분해 둡시다.

지금 다 외울 필요 없습니다. 본문에서 다시 만날 때 "아, 0장에 있었지" 하고 돌아오면 됩니다.

이 책의 척추 — 8~16장이 한 흐름으로 이어진다

이제 큰 그림입니다.

8~16장은 따로 노는 아홉 개의 주제가 아닙니다. "리소스를 점점 더 잘 다루는 법"이라는 하나의 줄기에서 뻗어 나온 가지들이에요.

이야기는 이렇게 흘러갑니다.

[리소스 하나를 알뜰하게 다루기]
   8장  필요한 필드만 주고받기 (부분 취득·부분 업데이트)
   9장  기본 동작으로 안 되는 특별한 일 시키기 (사용자 메서드)
        │
        ↓
[시간이 걸리거나 반복되는 일 안전하게 다루기]
   10장 오래 걸리는 일 추적하기 (장기 실행 작업)
   11장 실수로 두 번 눌러도 안전하게 만들기 (재수행 가능 작업)
        │
        ↓
[리소스에 딸린 것들 다루기]
   12장 부모마다 딱 하나뿐인 딸린 자원 (싱글톤 서브리소스)
        │
        ↓
[리소스끼리 이어 주기]
   13장 서로 가리키기 (교차 참조)
   14장 여럿이 여럿과 얽히고, 관계에 정보까지 담기 (연관 리소스)
   15장 관계를 가볍게 넣고 빼기 (add/remove)
        │
        ↓
[한 자리에 여러 타입 담기]
   16장 같은 자리에 여러 종류 받기 (다형성)

핵심 줄기를 한 문장으로 줄이면 이렇습니다.

하나의 리소스를 알뜰하게 다루는 법(8~9장)에서 시작해, 시간이 얽힌 일(10~11장), 딸린 자원(12장), 리소스끼리의 관계(13~15장)로 넓어지고, 마지막에 한 자리에 여러 타입을 담는 유연함(16장)으로 마무리됩니다.

각 장 한 줄 요약 — 지도 펼치기

아래 표가 이 책의 목차이자 지도입니다. 지금은 "이런 게 나오는구나" 정도만 훑어보세요. 자세한 건 각 장에서 천천히 풀립니다.

다음 장 예고

다음 8장에서는 "리소스 전체를 매번 주고받으면 왜 터지는지" 실패 장면부터 봅니다. 그 문제를 푸는 도구가 바로 위 표의 첫 줄 필드 마스크예요.

지금은 8장이 어떻게 동작하는지 몰라도 됩니다. 용어집과 지도를 한 번 훑어봤다는 것만으로 충분합니다.

한눈에 정리

0장이 한 일
─────────────────────────────────────
1. 어려운 용어 28개를 미리 쉬운 말로 풀었다
   (한 문장 뜻 + 일상비유 + 한 줄 예)

2. 8~16장이 하나의 줄기라는 걸 봤다
   리소스 알뜰히 → 시간 얽힌 일 → 딸린 자원
   → 리소스끼리 관계 → 여러 타입 담기

3. 각 장 한 줄 요약으로 지도를 그렸다

→ 이제 본문에서 모르는 단어가 나오면
  여기로 돌아오면 된다!